//
//  DPQualityAssurance.h
//  UITestingKit
//
//  Created by Ofri Wolfus on 19/03/07.
//  Copyright 2007 Ofri Wolfus. All rights reserved.
//

#import <Cocoa/Cocoa.h>
#import <UITestingKit/DPMacros.h>
#import <UITestingKit/DPAccessibilityNotificationCenter.h>
#import <UITestingKit/DPUIElement.h>


/*!
 * @abstract A base class for quality assurance objects.
 *
 * @discussion QA objects are automatically instantiated by UITestingKit
 * and are used to guard that the UI behaves as intended.
 * When an incorrect behaviour happens, the QA instance should throw an
 * exception that in turn, will terminate the testing process.
 *
 * QA objects may be either generic or specialized for a specific element.
 * A specialized QA object should override <code>+[DPQualityAssurance testedElement]</code>
 * to return the name  of the element it guards. Specialized elements will
 * be automatically created and destroyed together with their corresponding element.
 * Generic elements, on the other hand, are created before testing begins and
 * destroyed after testing ends.
 *
 * Unlike test cases, QA objects live while tests of all modules execute. Therefor,
 * they must remain consistent all the time.
 *
 * The actual "guarding" of an element is done by listening to accessibility
 * notifications posted to <code>DPAccessibilityNotificationCenter</code>.
 * Please refer to the NSAccessibility documentation and the UItestingKit
 * examples for more information.
 */
@interface DPQualityAssurance : NSObject {
	@private
	DPUIElement *_element;
}

/*!
 * @abstract Designated initializer.
 * @discussion You should never invoke this method directly, but may
 * override it to perform custom initialization (duh!).
 */
- (id)initWithElement:(DPUIElement *)element;

/*!
 * @abstract Override this method in your subclass to return the name of the UI
 * element it tests.
 *
 * @discussion The default implementation returns <code>nil</code>, which means
 * a generic QA object.
 */
+ (NSString *)testedElement;

/*!
 * @abstract If the receiver is a specialized QA object, this method returns its
 * UI element.
 *
 * @discussion For generic QA object, this method returns <code>nil</code>.
 */
- (DPUIElement *)UIElement;

@end
